NB If you are using this module under Risc OS kernel version 2.00 then you
must have IRQutils module v0.9 or greater loaded! This is because
DataPlay makes heavy usage of transient call backs and the 2.00 kernel
routines have an error in them that IRQutils fixes. Failure to load
this module can result in address exceptions and your machine crashing!
This module provides a means to have 'temporary' sounds that get played
once and then removed from memory. A typical application envisaged for this
would be a sound at startup of the machine. This module will remove the sample from memory when it is done playing. It relies on DataVox and DataLoad to function, complaining if they are not available...
One OSCLI command is provided. The syntax is :-
DataPlay_PlayFile <file> [-rmagrab <#Kb's to grab>] [-normashrink]
Where the file is *actually* a file and -rmagrab is totally optional. -rmagrab
claims a block of RMA *before* it tries to load the sample using DataLoad. Once
the sample is successfully loaded and play started it frees the block releasing
it back to the RMA. -normashrink stops DataPlay from minimising the RMA after playing the sample. This is occasionally useful.
Why do this? Well if DataPlay is near the begining of your boot sequence
it is highly likely you will be loading modules, sprites and other bits and
peices into the RMA. If there is insufficient free space available in the
RMA to satisfy these requests then the memory that the sample occupies will
be trapped in the middle of the RMA effectively useless to you. And given
that sound samples can easily occupy several hundred kilobytes this is not
desirable. By claiming an unused block first DataSuite will attempt to
ensure that enough free memory is available *below* the block claimed for
the sample to prevent blocks being allocated above it.
Obviously DataPlay has no idea what else you are loading so you must
tell it how much to claim. Of course if you are one of those smarmy bastards
who has 16 Megs you may not care much if a few hundred Kb gets trapped, so
this parameter is totally optional. When the sample has finished DataPlay
attempts to return as much of the RMA memory back to the application free
pool, just to be tidy.
DataPlay ensures sufficient channels are active etc and assigns the channels
correctly as it needs to. It handles stereo files as well automatically
claiming the needed resources and setting up the stereo assignments. All
channels are returned to their previous voice generator when play stops. (So
channel one will be returned back to wavesynth beep usually.)
And that about covers it. Simple eh?
Error Messages.
---------------
The Error range begins at &807100 and ends at &807108.
